sysuse auto
generate maker = substr(make, 1, strpos(make, " ")-1)
replace maker = make if strpos(make, " ")==0
label variable maker "Manufacturer"

* Text annotation
*	Outside the plot region
*		Titles, subtitle, notes, captions (help title_options)
*		Axis labels (variously defined:  variable labels,
*			axis titles, r1title/l1title)
*		Axis value labels (value labels, xaxis(range()), xlabel())
*		Legend value labels
*	Inside the plot region
*		Text as markers
*		Arbitrary text

scatter mpg weight, title("Gas Mileage") subtitle("Decreases with Weight") ///
	note("1978 data") caption("Figure 1")
* Numerous text options include using extended character sets (including
*	math symbols), specifying font face and size, repositioning text, etc. etc.

* Notice the axis labels are just the variable labels.  We can relabel
*	our data (help variable label), or we can have arbitrary
*	axis labels (help axis_title_options) that only affect our plot
scatter mpg weight, xtitle("Weight in pounds") ytitle("Miles per gallon")
* There are numerous options affecting the text as above, and also the
*	orientation of the lettering

* Notice in plots with categorical axes we do not have a categorical title
*	by default, and we are not allowed to use xtitle(), but we can use
*	b1title().
graph bar weight, over(maker)
capture noisily graph bar weight, over(maker) xtitle("Manufacturer") // error
graph bar weight, over(maker) b1title("Manufacturer")

* We probably want to rearrange those value labels (or consider a horiztonal
*	bar or dot plot!).  If we look at help graph bar, there do not appear
*	to be any/many useful x-axis options.  The options for the categorical
*	axes are lumped within the over() option - we can have different
*	labeling options for different levels of grouping!  
*	(help graph bar##over_subopts)
graph bar weight, over(maker, label(alternate)) b1title("Manufacturer") // not great
graph bar weight, over(maker, label(angle(45))) b1title("Manufacturer")

* Notice that rotated plots also rotate axis specifications
graph dot weight, over(maker, sort(weight) descending) ///
	l1title("Manufacturer") ytitle("Fleet Averge Weight")

* Axis value labels, which might equally be considered part of the
*	coordinate system, can be either numbers or other text.
scatter mpg weight, ylabel(10 "Guzzler" 20(5)30 40 "Sipper", angle(0))

* Labeling parts of the coordinate system where there are no data has
*	the side effect of changing the plotting range
scatter mpg weight, ylabel(0 "Junk" 10(10)40, angle(0))

*  But providing labels for only part of the data range does not 
*	reduce the plotting area
scatter mpg weight, ylabel(20(5)30)
* For that you need to take a subset
scatter mpg weight if mpg>20 & mpg<30

* Legends are another annotation like axis labeling.  The form a categorical
*	"coordinate" system, but they guide our understanding of symbols and
*	aesthetics rather than spatial positions.
* Any time you have two or more graph objects (a point and a line, two
*	separate layers of points, etc.) Stata will automatically produce
*	a legend.  This is a keyed table, where each symbol is paired with
*   some descriptive text.
separate mpg, by(foreign)
scatter mpg0 mpg1 weight
* In this example, the key text is provided by variable labels created
*	by the "separate" command.  We can replace these with the legend()
*	option.
scatter mpg0 mpg1 weight, legend(label(1 "Domestic") label(2 "Foreign"))
* The same effect can be acheived with
scatter mpg0 mpg1 weight, legend(order(1 "Domestic" 2 "Foreign"))
* We might want to add a ytitle and a legend title
scatter mpg0 mpg1 weight, legend(order(1 "Domestic" 2 "Foreign") ///
	subtitle("Car Source")) ytitle("Mileage (mpg)")

* Another level of annotation is labeling points within a plot.  This is
*	only useful in sparse plots!
* (help scatter##marker_options)
scatter mpg weight, mlabel(make) // not useful here!
* Sometimes you want text in place of markers.
generate plabel = "D" if foreign == 0
replace plabel = "F" if foreign == 1
* We center the label on the marker, and suppress the marker
scatter mpg weight, mlabel(plabel) mlabposition(0) msymbol(none)

* A similar idea is adding blabels to categorical plots

* We can add arbitrary text at an arbitrary point within the
*	plot region.  Notice the default has this text centered on
*	the specified point, and that we have to know something
*	about the coordinate system in order to specify any point.
scatter mpg weight, text(35 3500 "An expensive car" "costs you twice!", box)

* This might be coupled with a "pcarrowi" graph element to point to an
*	unusual observation
quietly summarize price
local maxcost = r(max)
quietly summarize weight if price == `maxcost'
local maxwgt = r(max)
quietly summarize mpg if price == `maxcost'
local maxmpg = r(mean)

twoway (scatter mpg weight, ///
	text(25 4500 "An expensive car" "costs you twice!", box)) ///
	(pcarrowi 25 4500 `maxmpg' `maxwgt'), ///
	legend(off) ytitle("Mileage (mpg)") xtitle("Weight (lbs.)")